SetRectRgn

SetRectRgn
Header:	Quickdraw.h		Carbon status:	Supported

Changes the structure of an existing region to that of a rectangle.

void SetRectRgn (
     rgn, 
    SInt16 left, 
    SInt16 top, 
    SInt16 right, 
    SInt16 bottom
);

Parameter descriptions

rgn: A handle to the region to restructure as a rectangle.
left: The horizontal coordinate of the upper-left corner of the rectangle to set as the new region.
top: The vertical coordinate of the upper-left corner of the rectangle to set as the new region.
right: The horizontal coordinate of the lower-right corner of the rectangle to set as the new region.
bottom: The vertical coordinate of the lower-right corner of the rectangle to set as the new region.

DISCUSSION

The SetRectRgn function destroys the previous structure of the region whose handle you pass in the rgn parameter, and it then sets the new structure to the rectangle that you specify in the left, top, right, and bottom parameters. If you specify an empty rectangle (that is, right is greater than or equal to left or bottom<=top), the SetRectRgn function sets the region to the empty region defined by the rectangle (0,0,0,0).

As an alternative to the SetRectRgn function, you can change the structure of an existing region to that of a rectangle by using the RectRgn function, which accepts as a parameter a rectangle instead of four coordinates.

If the points or rectangles supplied to this function are defined in a graphics port other than your current graphics port, you must convert them to the local coordinate system of your current graphics port. You can accomplish this by using the SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

SPECIAL CONSIDERATIONS

The SetRectRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.